package com.inibb.app.sftp;

import java.io.*;
import java.net.*;
import java.util.*;

import com.inibb.app.sftp.exception.SFTPException;
import com.inibb.app.sftp.exception.SFTPIOException;
import com.inibb.app.sftp.exception.SFTPLocalIOException;
import com.inibb.app.sftp.exception.SFTPRemoteFileNotFoundException;
import com.inibb.app.sftp.exception.SFTPRemoteIOException;




/**
 * This is the Interface Class for SFTP Connection.  
 * Object of this type can be instantiated by SFTPConnectionFactory. 
 * @author PCCW
 *
 */
public interface SFTPConnection
{
	/** The default port number (22) of SSH connections. */
	public static final int DEFAULT_SSH_PORT = 22;
	
	
	/**
	 * Make a SFTP connection to the target host and port with the given authentication info.
	 * @param addr - address of the target SFTP server
	 * @param port - port number of the target SFTP server
	 * @param auth - SFTPAuthInfo holding the credential for logging in the target SFTP server
	 * @throws SFTPIOException - When network related exception occurs
	 * @throws SFTPException - When SFTP related exception occurs
	 */
	public void connect(InetAddress addr, int port, SFTPAuthInfo auth)
		throws SFTPIOException, SFTPException
		;
		
	/**
	 * Make a SFTP connection to the target host using DEFAULT_SSH_PORT with the given authentication info.
	 * @param addr - address of the target SFTP server
	 * @param auth - SFTPAuthInfo holding the credential for logging in the target SFTP server
	 * @throws SFTPIOException - When network related exception occurs
	 * @throws SFTPException - When SFTP related exception occurs
	 */
	public void connect(InetAddress addr, SFTPAuthInfo auth)
		throws SFTPIOException , SFTPException
		;

	/**
	 * Disconnect the SFTP connection
	 * @throws SFTPIOException - When network related exception occurs
	 * @throws SFTPException - When SFTP related exception occurs
	 */
	public void disconnect()
		throws SFTPIOException , SFTPException
		;
	
	/**
	 * Retrieve the directory listing of given path
	 * @param path - the <code>RemoteFileEntry</code> point to the directory / file you want to list, use <code>null</code> for current directort.
	 * @return The the <code>List</code> holding the list of <code>RemoteFileEntry</code>.
	 * @throws SFTPRemoteFileNotFoundException - When remote file is not found
	 * @throws SFTPRemoteIOException - When I/O related exception occured in remote side
	 * @throws SFTPIOException - When network related exception occurs
	 * @throws SFTPException - When SFTP related exception occurs
	 */
	public List list(RemoteFileEntry path)
		throws SFTPRemoteFileNotFoundException, SFTPRemoteIOException, SFTPIOException , SFTPException
		;
	
	/**
	 * Change the remote directory to the given path.
	 * @param path - the targer remote directory in <code>String</code>
	 * @return the current remote directory
	 * @throws SFTPRemoteFileNotFoundException - When remote file is not found
	 * @throws SFTPRemoteIOException - When I/O related exception occured in remote side
	 * @throws SFTPIOException - When network related exception occurs
	 * @throws SFTPException - When SFTP related exception occurs
	 */
	public RemoteFileEntry changeDir(String path)
		throws SFTPRemoteFileNotFoundException, SFTPRemoteIOException, SFTPIOException , SFTPException
		;

	/**
	 * Change the remote directory to the given path.
	 * @param path - the targer remote directory in <code>RemoteFileEntry</code>
	 * @return the current remote directory
	 * @throws SFTPRemoteFileNotFoundException - When remote file is not found
	 * @throws SFTPRemoteIOException - When I/O related exception occured in remote side
	 * @throws SFTPIOException - When network related exception occurs
	 * @throws SFTPException - When SFTP related exception occurs
	 */
	public RemoteFileEntry changeDir(RemoteFileEntry path)
		throws SFTPRemoteFileNotFoundException, SFTPRemoteIOException, SFTPIOException , SFTPException
		;

	/**
	 * Get the remote current directory
	 * @return <code>RemoteFileEntry</code> of remote current directory.
	 * @throws SFTPIOException - When network related exception occurs
	 * @throws SFTPException - When SFTP related exception occurs
	 */
	public RemoteFileEntry pwd()
		throws SFTPRemoteIOException, SFTPIOException , SFTPException
		;
	
	/**
	 * Remove the remote file.
	 * @param file - the <code>RemoteFileEntry</code> pointing to the remote file to be deleted.
	 * @throws SFTPRemoteFileNotFoundException - When remote file is not found
	 * @throws SFTPRemoteIOException - When I/O related exception occured in remote side
	 * @throws SFTPIOException - When network related exception occurs
	 * @throws SFTPException - When SFTP related exception occurs
	 */
	public void remove(RemoteFileEntry file)
		throws SFTPRemoteFileNotFoundException, SFTPRemoteIOException, SFTPIOException , SFTPException
		;
	
	/**
	 * Remove the remote directory.
	 * @param file - the <code>RemoteFileEntry</code> pointing to the remote directory to be deleted.
	 * @throws SFTPRemoteFileNotFoundException - When remote file is not found
	 * @throws SFTPRemoteIOException - When I/O related exception occured in remote side
	 * @throws SFTPIOException - When network related exception occurs
	 * @throws SFTPException - When SFTP related exception occurs
	 */
	public void removeDir(RemoteFileEntry dir)
		throws SFTPRemoteFileNotFoundException, SFTPRemoteIOException, SFTPIOException , SFTPException
		;
	
	/**
	 * Rename or Move the remote file or directory
	 * @param source - the original remote file / directory to be renamed / moved.
	 * @param target - the target remote file / directory 
	 * @throws SFTPRemoteFileNotFoundException - When remote file is not found
	 * @throws SFTPRemoteIOException - When I/O related exception occured in remote side
	 * @throws SFTPIOException - When network related exception occurs
	 * @throws SFTPException - When SFTP related exception occurs
	 */
	public void rename(RemoteFileEntry source, RemoteFileEntry target)
		throws SFTPRemoteFileNotFoundException, SFTPRemoteIOException, SFTPIOException , SFTPException
		;
	
	/**
	 * Create a remote directory
	 * @param dir - the directory to be created
	 * @throws SFTPRemoteIOException - When I/O related exception occured in remote side
	 * @throws SFTPIOException - When network related exception occurs
	 * @throws SFTPException - When SFTP related exception occurs
	 */
	public void mkdir(RemoteFileEntry dir)
		throws SFTPRemoteIOException, SFTPIOException , SFTPException
		;
	
	/**
	 * Put a local file to remote destination
	 * @param source - the file to be put
	 * @param dest - the remote target destination of the file 
	 * @throws SFTPLocalIOException - When I/O related exception occured in local side
	 * @throws SFTPRemoteIOException - When I/O related exception occured in remote side
	 * @throws SFTPIOException - When network or I/O related exception occurs
	 * @throws SFTPException - When SFTP related exception occurs
	 */
	public void put(File source, RemoteFileEntry dest)
		throws SFTPLocalIOException, SFTPRemoteIOException, SFTPIOException , SFTPException
		;
	
	/**
	 * Get a remote file
	 * @param source - the remote source file to be retrieved
	 * @param dest - the local target destination of the file.
	 * @throws SFTPLocalIOException - When I/O related exception occured in local side
	 * @throws SFTPRemoteFileNotFoundException - When remote file is not found
	 * @throws SFTPRemoteIOException - When I/O related exception occured in remote side
	 * @throws SFTPIOException - When network or I/O related exception occurs
	 * @throws SFTPException - When SFTP related exception occurs
	 */
	public void get(RemoteFileEntry source, File dest)
		throws SFTPLocalIOException, SFTPRemoteFileNotFoundException, SFTPRemoteIOException, SFTPIOException , SFTPException
		;
	
	/**
	 * Return the connection status.
	 * @return
	 */
	public boolean isConnected() ;
	
	/**
	 * Set to turn on / off None Cipher Mode.  
	 * None Cipher Mode will try to disable enryptions when sending data between client and server.
	 * This options depends on SFTPConnection and server implementation.
	 * (Should be set before connect)
	 * @param b - set to true for turning on None Cipher Mode; false otherwise.
	 */
	public void setNoneCipherMode(boolean b);
	
	/**
	 * Set the implementation specific configurations.
	 * (Should be set before connect)
	 * @param config
	 */
	public void setConfig(Hashtable config) ;
}
